home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Discy Business / Discy Business.2mg / DEV.CD / develop / develop.3 / CDAUDI.306. < prev    next >
Encoding:
Text File  |  1990-05-25  |  18.4 KB  |  285 lines  |  [04] ASCII Text (0x0000)
  1. ACCESSING CD-ROM AUDIO TRACKS FROM YOUR APPLICATION
  2.  
  3. CD-ROM opens up the possibility of providing the user of your application with a new dimension of sound feedback, in full digitally reproduced stereo. Coaxing the sound out of the AppleCD SCr drive, however, is not as simple as prompting the user to "press PLAY on 
  4. your CD-ROM drive now." This article explains the intricacies of controlling the audio functions of the AppleCD SC from an Apple II application.
  5. Imagine how you might use CD-ROM audio tracks to make your software burst with sound: language software that pronounces each lesson as it teaches it; reading programs that speak words instead of just displaying them; almost any kind of program adapted with audio cues for an audience with reading disabilities.  
  6. CD-ROM is also the answer for applications that require lengthy music tracks or background music that simply won't fit on the program disk in a digitized format.
  7.  
  8. In this article, you'll learn about the capabilities of the AppleCD SC drive, and the kinds of calls you can make to the drive to control the audio features. The article also covers basic information about how audio tracks are stored on CD-ROM. (While the primary focus of this article is the Apple II, this section applies to the Macintosh as well.) Finally, it covers the specifics of playing audio tracks via the GS/OSr SCSI CD driver and the five major audio control calls. 
  9. AN OVERVIEW OF THE AUDIO CAPABILITY
  10. You make the AppleCD SC do your bidding by sending it the GS/OS device calls DStatus and DControl via the GS/OS SCSI CD driver. These calls enable you to control all features of the drive.
  11.  
  12. You get information about the contents of the disc in the drive and the current status of the drive with two DStatus subcalls: ReadTOC and AudioStatus. 
  13.  
  14. You control audio play with five DControl subcalls: AudioPlay, AudioPause, AudioScan, AudioStop, and AudioSearch. These calls start and stop the disc from spinning inside the AppleCD SC, and position the laser.
  15.  
  16. We'll look at each of these functions in greater detail in the sections that follow, and illustrate them with code for a CD Remote classic desk accessory (CDA).  You'll find the complete source code on the Developer Essentials disc in Merlin 16+ format.  This code serves three purposes: first, it enables you to experiment with the AppleCD SC drive and see how it responds to certain calls. Second, it documents the exact steps necessary to make audio calls. Finally, you can modify and extend it with your own test code. 
  17. TO COMMUNICATE WITH THE DRIVE
  18. Your Apple II application can communicate with the AppleCD SC through calls built into either the SmartPort or the GS/OS SCSI CD driver. Accessing the AppleCD SC's audio features via the Smartport or from the Macintosh side of things is very well documented, while documentation about using the GS/OS SCSI CD driver is not as complete (yet).  We'll focus here on how to access the AppleCD SC via GS/OS. 
  19.  
  20. Issuing CD SC commands from your program is a two-step process: first you must locate the drive with a DInfo call, and then you can use DStatus and DControl to check the status and control the device. The control data you send will be parameter lists for the audio calls; the status data you receive will be information about the disc in the drive. 
  21. DInfo
  22. Locating the drive with DInfo is fairly straightforward: you step through each of the available devices until you find one that has a deviceIDNum of $0007 (SCSI CD ROM drive). If your DInfo call returns an error $11, that means that you've hit the end of the device chain, and that no CD SC drive is hooked up.
  23.  
  24. Here is an example from the sample program of how to locate the attached AppleCD SC drive:
  25.  
  26. FindCDRom
  27.          lda   CDROMDev   ;Have we found it before?
  28.          bne   :leave     ;Yes - leave now.
  29.  
  30. :look                     ;Start looking for drive.
  31.          jsl   GSOS
  32.          dw    DInfo      ;Make GS/OS DInfo call.
  33.          adrl  :devParm
  34.          bcs   :err       ;Leave if error.
  35.  
  36.          lda   devID      ;Get device ID.
  37.          cmp   #$0007     ;Is it a SCSI CD-ROM device?
  38.          beq   :found     ;Yes - found it.
  39.  
  40.          inc   devNum     ;No - move to next device . . .
  41.          bra   :look      ;and keep looking.
  42.  
  43. :found   lda   devNum
  44.          sta   CDROMDev
  45.          sta   DCdevNum   ;Store device number for all control calls.
  46.          sta   DSdevNum   ;Store device number for all status calls.
  47. :leave   clc              ;Found it.
  48.          rts
  49.  
  50. :none    ~WriteCString #:noCDRom
  51. :1       jsr   getKey
  52.          sec              ;None found!
  53.          rts
  54.  
  55. :err     cmp   #$11       ;Error $11 - invalid device number?
  56.          beq   :none      ;Yes - no CD-ROM drive found!
  57.          ~WriteCString #:error ;No - some other weird error.
  58.          bra   :1
  59.  
  60. :error   asc   0d'GS/OS error on DInfo call. Press any key to quit. '0700
  61. :noCDRom asc   0d'No CD-ROM drive found. Press any key to quit. '0700
  62.  
  63. :devParm dw    8          ;Eight parameters.
  64. devNum   dw    1          ;Device number - start with 1.
  65.          adrl  nameBuffer ;Pointer to buffer for device name.
  66.          dw    0          ;Characteristics.
  67.          dl    0          ;TotalBlocks.
  68.          dw    0          ;SlotNum.
  69.          dw    0          ;UnitNum.
  70.          dw    0          ;Version.
  71. devID    dw    0          ;Device ID: $0007 = SCSI CD-ROM.
  72.  
  73. nameBuffer dw  31         ;Max length.
  74.          ds    33         ;Storage for device name.
  75.  
  76.  
  77. Dstatus AND Dcontrol
  78. Once you've found the drive, exchanging information with it is simply a matter of DStatus and DControl calls. DStatus enables you to receive status data from the drive; DControl enables you to send control data to the drive. 
  79. The main parameter table for DControl and DStatus contains a parameter count, the device number you're working with, the control (or status) code, a pointer to the command data, a request count (used for status calls), and a transfer count.
  80.  
  81. The command data information is a parameter list of 18 bytes (see Figure 1).  The first two are reserved and must be 0; the following byte is the SCSI command (which is the same as the control/status code low byte). Next is a block of 11 bytes: these are specific to each call. Finally, the command data parameter list ends with a long pointer to another buffer, where SCSI data is returned from the status calls. 
  82. Figure 1
  83. Command Data for DStatus and DControl
  84. The following code from the sample program implements two handlers to make DControl and DStatus calls:
  85.  
  86. * Make a DControl call - enter with control code in accumulator.
  87.  
  88. DoDControl
  89.       sta   DCcode     ;Store control code.
  90.       shortacc
  91.       sta   controlData ;Store it in start of the parameter list.
  92.       longacc
  93.  
  94.       jsl   GSOS
  95.       dw    DControl   ;Make GS/OS DControl call.
  96.       adrl  :devParm
  97.  
  98.       jsr   GDS        ;Get device status & set new disc flag, if necessary . . .
  99.  
  100.       rts              ;and return with the call made.
  101.  
  102. :devParm dw    5       ;Parm list for the DControl call.
  103. DCdevNum dw    0       ;Fill in device number here.
  104. DCcode   dw    0       ;Control code.
  105.       adrl  controlList ;Pointer to buffer.
  106.       dl    0          ;RequestCount - unused.
  107.       dl    0          ;TransferCount.
  108.  
  109. controlList dw 0       ;Reserved.
  110. controlData ds 12      ;12 bytes of data.
  111.       adrl  buffer     ;Pointer to buffer.
  112. buffer   ds    20
  113.  
  114. * Make a DStatus call - enter with status code in accumulator.
  115.  
  116. DoDStatus
  117.       sta   DScode     ;Store control code.
  118.       shortacc
  119.       sta   statusData ;Store it in start of the parameter list.
  120.       longacc
  121.  
  122.       jsl   GSOS
  123.       dw    DStatus    ;Make GS/OS DStatus call.
  124.       adrl  statParm
  125.  
  126.       jsr   GDS        ;Get device status & set new disc flag, if necessary . . .
  127.  
  128.       rts              ;and return with the call made.
  129. statParm dw    5       ;Parm list for the DStatus call.
  130. DSdevNum dw    0       ;Fill in device number here.
  131. DScode   dw    0       ;Status code.
  132.       adrl  statusList ;Pointer to buffer.
  133. DSrequest dl   0       ;RequestCount.
  134.       dl    0          ;TransferCount.
  135.  
  136. statusList dw  0       ;Reserved.
  137. statusData ds  12      ;12 bytes of data.
  138.       adrl  buffer     ;Pointer to buffer.
  139.  
  140. TO FIND OUT MORE ABOUT THE DISC IN THE DRIVE
  141. The AppleCD SC has two important calls for finding out more about the disc in the drive: ReadTOC (to read the table of contents) and AudioStatus (to find out exactly what the drive is doing). These calls are useful immediately after the user has inserted a new (foreign) disc, to ascertain the disc's layout and whether the disc is currently playing, searching, paused, or muted.  They are also useful in the case where you've placed one application on several different discs, each with a different audio track layout.  
  142. ReadTOC
  143. The ReadTOC call can return data in three ways, known as types $00, $01, and $02. You specify the type in the ReadTOC parameter list.
  144.  
  145. A type $00 table of contents returns the value of the first and last tracks available on the disc. Tracks are numbered consecutively, starting with 1, and the type $00 table of contents always returns $01 as the value for the first track on the disc. 
  146.  
  147. Type $01 gives you the disc lead-out time in minutes, seconds, and blocks. (The lead-out time is the total time of all tracks on the disc, including the data track, if one exists.)
  148.  
  149. Finally, type $02, the most flexible of the three, returns starting address information (control field, minutes, seconds, and blocks) for each track on the disc. You can specify how many bytes the call will return and which track to start on, which makes it possible to find out about a single track instead of all of the tracks on the disc.
  150.  
  151. Examples of using the ReadTOC call can be found in the "NewDisc" and "Play" routines of the accompanying source code. 
  152.  
  153. AudioStatus
  154. The AudioStatus call returns the current status of the drive, the current play mode, the control field of the current track, and the Q Subcode for either the next track on the disc (if a track is currently playing) or the current track (if a track is not currently playing). 
  155.  
  156. The current status of the drive is reported as one of six messages: AudioPlay operation in progress, Pause operation in progress, Muting On operation in progress, AudioPlay completion status, Error during AudioPlay operation status, or AudioPlay operation not requested. 
  157.  
  158. The play mode is how audio will be output.  It has the following possible values:
  159.  
  160. Bits
  161. 3210    Effect
  162. 0000    Muting on (no audio)
  163. 0001    Right channel through right channel only
  164. 0010    Left channel through right channel only
  165. 0011    Both channels through right channel only
  166. 0100    Right channel through left channel only
  167. 0101    Right channel through left and right channel
  168. 0110    Right channel through left channel, left channel through right channel (reversed)
  169. 0111    Right channel through left channel, both channels through right channel
  170. 1000    Left channel through left channel only
  171. 1001    Left channel through left channel, right channel through right channel (stereo)
  172. 1010    Left channel through left and right channels
  173. 1011    Left channel through left channel, both channels through right channel
  174. 1100    Both channels through left channel
  175. 1101    Both channels through left channel, right channel through right channel
  176. 1110    Both channels through left channel, left channel through right channel
  177. 1111    Both channels through left channel, both channels through right channel (mono)
  178.  
  179. The control field describes the format of the current track, and has the following possible values:
  180.  
  181. Bits
  182. 3210    Effect
  183. 00x0    Two audio channels without preemphasis
  184. 00x1    Two audio channels with preemphasis
  185. 10x0    Four audio channels without preemphasis
  186. 10x1    Four audio channels with preemphasis
  187. 01x0    Data track
  188. 01x1    Reserved
  189. 11xx    Reserved
  190. xx0x    Digital copy prohibited
  191. xx1x    Digital copy permitted
  192. The Q Subcode is the absolute address of either the next track on the disc (if a track is currently playing) or the current track (if a track is not currently playing). It consists of the track starting address in minutes, seconds, and blocks. With the Q Subcode, you can quickly tell where the laser is positioned.
  193.  
  194. Here is a short example of getting the drive status and reporting it to the user:
  195.  
  196. Status
  197.          ~WriteCString #:stat
  198.  
  199.          jsr   ZeroParamList ;Zap old parameter list.
  200.  
  201.          lda   #$0006        ;Get six bytes from AudioStatus.
  202.          sta   DSrequest
  203.          lda   #AudioStatus  ;Make this call.
  204.          jsr   DoDStatus
  205.          shortacc
  206.          lda   buffer        ;Get audio status.
  207.          longacc
  208.          cmp   #5+1
  209.          bge   :bad
  210.          asl                 ;*2 so offset into table is correct.
  211.          tay
  212.          lda   #^:msgPtrs    ;Get current bank.
  213.          pha                 ;Push high word.
  214.          lda   :msgPtrs,y    ;Push low word.
  215.          pha
  216.          _WriteCString       ;Print string.
  217.          clc
  218.          rts
  219.  
  220. :bad     ~WriteCString #:unk
  221.          clc
  222.          rts
  223.  
  224. :stat    asc   'Status'0d0d00
  225. :unk     asc   'Unknown audio status returned'0d00
  226. :msgPtrs
  227.          dw    :nowPlay      ;$00
  228.          dw    :pause        ;$01
  229.          dw    :muting       ;$02
  230.          dw    :playComp     ;$03
  231.          dw    :errPlay      ;$04
  232.          dw    :noPlay       ;$05
  233.  
  234. :nowPlay asc   'AudioPlay operation in progress'0d00
  235. :pause   asc   'Pause operation in progress'0d00
  236. :muting  asc   'Muting On operation in progress'0d00
  237. :playComp asc  'AudioPlay completion status'0d00
  238. :errPlay asc   'Error occurred during AudioPlay operation'0d00
  239. :noPlay  asc   'AudioPlay operation not requested'0d00
  240. TO PLAY AUDIO TRACKS
  241. Five main audio calls are available to the programmer to control the audio features of the AppleCD SC drive: 
  242.  
  243. AudioPlay   This call enables you to start the drive on an audio playback operation (you pass it the play mode), or to specify a stop address for audio playback.
  244.  
  245. AudioStop   Like AudioPlay, this call enables you to specify a stop address for audio playback. AudioStop can be used to set up a stop address prior to issuing an AudioPlay call starting playback.
  246.  
  247. AudioPause  This call enables you to temporarily stop the audio playback operation by turning on muting and holding the laser over the same Q Subcode address. AudioPause also enables you to resume the audio playback operation after it has been stopped with a previous AudioPause operation. This call is useful if you wish to pause audio playback on the fly and resume it instantly, without any delay.
  248.  
  249. AudioSearch This call enables you to position the laser over an address on the disc (a specified track or Q Subcode). This can be useful if it is crucial that your application be able to start playback at a certain time: you can first search to the specific track and then hold the disc there, later issuing an AudioPlay command (which will begin play immediately). AudioSearch can also be set to start playing as soon as the specified address is located.
  250.  
  251. AudioScan   This call causes a fast-forward or fast-reverse scan operation, 
  252. starting from the address passed to it. 
  253.  
  254.  
  255. The steps to play an audio track from your application are fairly straightforward: 
  256.  
  257. 1.  Choose the last track you wish to play and set it with the AudioStop command. 
  258. 2.  Choose the first track you wish to play and pass it to AudioPlay with the stop flag set to 0. 
  259. If you wish to play a single track, pass the same track number for both commands. If you want to simply start playback on a given track and allow the disc to play to the end, pass the last track number to AudioStop and the track to begin playback on to AudioPlay. (The last track number can be retrieved with a type $00 ReadTOC command.)
  260. The AudioScan call is useful if you're allowing the user to directly control the disc from the application; otherwise, there is little need to fast-forward or fast-rewind when your program is already aware of the layout of the disc. AudioPause and AudioSearch are two practical ways to prepare the disc for playback without delay, and then pause and resume it. By using AudioSearch before your program needs to begin playback, you can have the disc spinning and the laser positioned exactly where it needs to be. 
  261. TO SUM IT ALL UP
  262. By now, you're familiar with the many advantages and possibilities that CD-ROM audio access can provide your application. You know the layout of an audio track on CD-ROM and how to find out more about the track from your application.
  263.  
  264. You know the five major audio calls and a handful of supporting calls. You know what they can do for you and why you might want to use them.
  265.  
  266. You're ready to produce an application that takes full advantage of the AppleCD SC drive, equipping your program with the ability to produce sound and music of unequaled quality.
  267.  
  268. -----------
  269.  
  270.  
  271. ABOUT CD-ROM AUDIO TRACK FORMAT
  272.  
  273. Audio data on a CD-ROM is stored in tracks. A CD can have a maximum of 99 tracks. Each track is broken down into minutes, seconds, blocks, frames, and finally, bytes, as shown in Figure 2. Tracks are numbered consecutively starting with 1, while minutes, seconds, blocks, and frames are numbered consecutively starting with 0.  
  274.  
  275. This format enables exact specification of a location on a CD-ROM.  A location can be specified by absolute block number (for example, start playing at absolute block 1,234,567 from the start of the disc), or by absolute minute, second, and block number (for example, start 
  276. playing at minute 42, second 30, block 15 on the disc), or by logical track number (for example, start playing 
  277. at track 2).
  278.  
  279. Note that blocks are often referred to as frames in 
  280. CD-ROM industry documentation; following that lead, you'll see references to disc data in minute-second-frame format in my source code when it's truly in minute-second-block format. There is no way to access individual frames (1/98th of a block) or bytes of the disc with the AppleCD SC drive; however, for audio playback, it is unnecessary and presents no handicap. 
  281.  
  282. ---------
  283.  
  284. Eric Mueller  is a free-lance Apple II programmer (with an interest in telecommunications) who leads an unstructured life with no days off, no days on. Despite that, he doesn't seem to have much free time. He plans to go to college somewhere, someday, to study the great unknown. For now, he writes his code, co-manages an Apple II area on GEnie, listens to the B-52's, eats lunch in Chinese restaurants, and watches "Late Night With David Letterman." During his days off (or is it his days on?) he enjoys teaching "stupid pet tricks" to his two cats, Conan and Aster, and enjoys life in Colorado Springs. Otherwise, he gets perverse thrills by writing Apple II programs that don't go at all "by the book." (He does promise that he absotively, posilutely has memorized the interface guidelines, a MUST in the curriculum of the 
  285. great unknown.) o